Fix MCP tool name conflicts by adding server name prefixes #1178
+395
−25
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Problem: - When multiple MCP servers have tools with the same name, agent list MCP would hang - Tool name conflicts made it impossible to distinguish tools from different servers - This caused the agent SDK to malfunction when listing tools Solution: - Add server name prefixes to tool names (e.g., server1_run, server2_run) - Store original tool names in 'original_name' attribute for actual tool calls - Maintain backward compatibility - tool invocation still uses original names - Handle edge cases like empty server names and special characters Changes: - Modified src/agents/mcp/server.py: Added tool name prefixing in list_tools() - Modified src/agents/mcp/util.py: Updated invoke_mcp_tool() to use original names - Enhanced call_tool() to handle both prefixed and original tool names - Added comprehensive logging for debugging This resolves the hanging issue and ensures tools from different servers are properly distinguished while maintaining full backward compatibility.
|
At a glance, the changes look good to me. Can you resolve the lint and typecheck failures? |
|
Okay, I'll try it. |
…name and handle both prefixed and original names. Updated invoke_mcp_tool method in util.py to ensure calls are made using original tool names. Added test cases in test_tool_name_conflicts.py to verify the correctness of tool name prefixes and preservation of original names.
|
Can you check the mypy errors in tests? |
|
Ok, I will handle these errors. |
@fadeoreo if you need help, I can fix this. |
|
There are still lint issues: |
rm-openai
requested changes
Jul 24, 2025
|
Okay, I'll add it and update the code |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Problem
When two MCP servers have tools with the same internal tool name, running
agent list MCP: list tools from server xxxxwill hang, and after the tool list is (supposedly) returned, the agent cannot work properly.During troubleshooting, issues such as network, protocol, registration, or async problems were suspected, but the real cause was that one of the MCP tools had a conflicting tool name, making it impossible for the agent SDK to distinguish between tools from different servers.
Solution
This PR implements server name prefixing for MCP tool names to ensure global uniqueness and avoid conflicts:
{server_name}_{tool_name}format (e.g.,serverA_run,serverB_run)original_nameattribute for actual tool callsChanges Made
Core Implementation
src/agents/mcp/server.py: Modifiedlist_tools()method to add server name prefixes and preserve original namessrc/agents/mcp/util.py: Updatedinvoke_mcp_tool()to use original names for tool callsTesting
tests/mcp/test_tool_name_conflicts.py: Comprehensive test suite with 9 test cases covering:Example
Before (Conflict)
Server1: [run, echo]
Server2: [run, list]
Result: ❌ Conflict on 'run' tool name → agent list hangs
After (Resolved)
Server1: [server1_run, server1_echo]
Server2: [server2_run, server2_list]
Result: ✅ All tool names are unique → agent list works correctly
Fixes #1167